feat(auth): Add blocking Regional Access Boundary Lookup and Seed Support by macastelaz · Pull Request #16720 · googleapis/google-cloud-python

macastelaz · 2026-04-20T14:12:46Z

In order for the gcloud CLI to support Regional Access Boundary, the Python auth SDK needs to support blocking lookups as well as allowing an initial seed RAB to be provided (gcloud will set this seed if the CLI has a locally cached valid RAB available).

Additional details can be found at go/rab-python-gcloud-one-pager

gemini-code-assist

Code Review

This pull request renames the "Trust Boundary" feature to "Regional Access Boundary" (RAB) and introduces a centralized management system for it. Key changes include the implementation of _RegionalAccessBoundaryManager for thread-safe state handling and background refreshes, and the update of multiple credential types to support this new mechanism. The with_trust_boundary method is deprecated in favor of with_regional_access_boundary. Review feedback recommends updating a type hint in the utility module to correctly reflect the expected data types and removing redundant error logging in the base credentials class to reduce log noise.

…undary implementation

…ystem tests

Renamed 'with_regional_access_boundary' to '_with_regional_access_boundary' to indicate internal use.

Update the comment block of "_with_regional_access_boundary" to inform future maintainers of the necessity to maintain a backwards compatible contract of this method.

…__eq__

nbayati

Overall looks really good! Just a few small comments and questions.

- Add test for token refresh and RAB lookup sequencing in before_request. - Add failure test to verify blocking RAB lookups are not retried. - Restore and refine test for skipping RAB lookup when URL is None. - Fix swapped url/method arguments in before_request test calls. - Document why OAuth2 credentials skip independent RAB lookups. - Internalize blocking lookup method with leading underscore.

nbayati

Great job!

daniel-sanche · 2026-04-29T20:34:55Z

/gemini review

gemini-code-assist

Code Review

This pull request introduces support for blocking regional access boundary (RAB) lookups and allows for seeding RAB data manually. Key changes include updates to the _RegionalAccessBoundaryManager to handle blocking refreshes, modifications to the Credentials class to support these new lookup modes, and adjustments to the OAuth2 client to implement configurable timeouts and retry logic for blocking requests. A critical issue was identified in the before_request implementation within the CredentialsWithRegionalAccessBoundary mixin, which currently relies on OAuth2-specific attributes and will cause failures for other credential types. Additionally, a docstring type hint for the seed parameter should be updated to Mapping[str, Any] to correctly reflect that the expiry key contains a datetime object.

gemini-code-assist · 2026-04-29T20:37:49Z

+        if self._use_non_blocking_refresh:
+            self._non_blocking_refresh(request)
+        else:
+            self._blocking_refresh(request)


This implementation of before_request in the CredentialsWithRegionalAccessBoundary mixin is too specific to OAuth2 credentials. It relies on attributes like _use_non_blocking_refresh and methods like _non_blocking_refresh which are not present in the base Credentials class or other subclasses (e.g., ComputeEngineCredentials). This will cause an AttributeError when used with non-OAuth2 credentials.

Instead of duplicating the refresh logic, you should call super().before_request(). This allows the mixin to remain generic while still ensuring that the token is refreshed before the Regional Access Boundary lookup is triggered.

super(CredentialsWithRegionalAccessBoundary, self).before_request( request, method, url, headers )

This is worth confirming, but from my understanding, I'm not sure if this is an issue. CredentialsWithRegionalAccessBoundary inherits from Credentials, so it should have those internal attributes.

It does seem a little dangerous that before_request seems to be mostly copy/pasted from the superclass here though. I wonder if that can be cleaned up somehow? I could see these drifting over time

Yes I think Gemini's assessment is incorrect. We had to duplicate the parent's logic here because we needed to ensure that the RAB lookup (which might be blocking) happens after the access token is refreshed but before headers are applied to the request. Credentials.before_request does both (refresh and apply) in one go.

I agree with the concern that they might drift over time. I think this can be refactored in the future and extract the common logic into a helper method. Would you be ok with us merging it as-is now, and doing the refactoring in the future?

daniel-sanche

a bunch of small comments, and a few that are worth looking at closer. I know there's a bit of time pressure on this, so you can ignore some of the nits if needed

daniel-sanche · 2026-04-29T20:34:25Z

+
+    def use_blocking_regional_access_boundary_lookup(self):
+        """Enables blocking regional access boundary lookup to true"""
+        self._use_blocking_regional_access_boundary_lookup = True


I think this naming could get very confusing, since this is a state-changing function with an (almost) identical name to an internal data attribute. And the docstring isn't helpful

Can we change the function name to something like enable_blocking_lookup? And make the docstring explain what happens when this is enabled?

daniel-sanche · 2026-04-29T20:37:35Z

+            seed (Mapping[str, str]): The regional access boundary to use for the
+                credential. This should be a map with, at a minimum, an "encodedLocations"
+                key that maps to a hex string and an "expiry" key which maps to a
+                datetime.datetime.


the docstring makes it sound like these fields required, but the code seems to work fine if they're not

why are we using a map for this? why not make encoded_locations and expiry arguments?

Both are very valid. I made the fields arguments here, but kept the map for _with_regional_access_boundary(self, seed) since this is the method gcloud cli will be using.

daniel-sanche · 2026-04-29T20:42:40Z

-        """
-        Performs the Regional Access Boundary lookup and updates the state.
+    def start_blocking_refresh(self, credentials, request):
+        """Initiates a blocking lookup of the Regional Access Boundary.


nit: the docstring should probably mention what happens on an exception

daniel-sanche · 2026-04-29T20:47:34Z

        Args:
            request (google.auth.transport.Request): The object used to make
                HTTP requests.
+            blocking (bool): Whether the lookup should be blocking.


nit: more context would be helpful (e.g. "otherwise, the lookup will be preformed in a background thread", or something)

The thread is spawned and managed by the caller (specifically by the _RegionalAccessBoundaryRefreshManager), and setting blocking here to true or false doesn't affect if it's run on the background or current thread.

daniel-sanche · 2026-04-29T20:55:16Z

+class _RegionalAccessBoundaryRefreshThread(threading.Thread):
+    """Thread for background refreshing of the Regional Access Boundary."""
+
+    def __init__(self, credentials, request, rab_manager):


nit: typing could be helpful here. (Does this only work with CredentialsWithRegionalAccessBoundary credentials?)

Yes, it only work with CredentialsWithRegionalAccessBoundary credential. I'm adding string literal type hints to avoid making a circular dependency.

daniel-sanche · 2026-04-29T21:11:25Z

+        if self._use_non_blocking_refresh:
+            self._non_blocking_refresh(request)
+        else:
+            self._blocking_refresh(request)


This is worth confirming, but from my understanding, I'm not sure if this is an issue. CredentialsWithRegionalAccessBoundary inherits from Credentials, so it should have those internal attributes.

It does seem a little dangerous that before_request seems to be mostly copy/pasted from the superclass here though. I wonder if that can be cleaned up somehow? I could see these drifting over time

daniel-sanche · 2026-04-29T21:14:34Z

        url (str): The Regional Access Boundary lookup url.
        can_retry (bool): Enable or disable request retry behavior. Defaults to true.
        headers (Optional[Mapping[str, str]]): The headers for the request.
+        blocking (bool): Whether the lookup should be blocking.


Doesn't it block in all cases here? It seems like "blocking" in this case just controls how timeout/retry configuration?

I'm pretty confused by this, because it seems like it uses a much lower timeout and retry configuration when blocking is enabled, which is pretty much the opposite from what I would expect (1x 3 second attempt for blocking, vs 6x 120 second attempts for non-blocking)

Thanks for pointing this out. I think the parameter name was a bit misleading.

The shorter timeout and no retry was an intentional choice because on gcloud has to use the blocking mode, which blocks the user's foreground action, and we want to fail fast (3s timeout, no retries) to avoid freezing the terminal for a long time if the endpoint is slow or down. The RAB fetching is a best effort operation, where we try to get the header to improve the call's routing and latency, but if it fails or is taking a long time, we'd want to let the call to go through without further delays.

I've renamed the parameter in the internal lookup methods from blocking to fail_fast to better describe the behavior, and updated the docstrings in credentials.py and _client.py to explicitly mention that fail_fast=True uses a short timeout and no retries.

daniel-sanche · 2026-04-29T21:23:05Z

+        Returns:
+            None: This credential type does not support RAB lookup.
+        """
+        return None


If this always returns None, it looks like this could result in a lot of failure logs here. In that context, None seems to represent a failure

Should this class overrride _is_regional_access_boundary_lookup_required to disable lookup? Or am I misunderstanding this?

Great catch! Thank you for flagging this and the suggestion! I've added the overrride to _is_regional_access_boundary_lookup_required to return False. This ensures we don't attempt to call _build_regional_access_boundary_lookup_url, and would resolve the failures being logged.

daniel-sanche

LGTM

gemini-code-assist Bot reviewed Apr 20, 2026

View reviewed changes

Comment thread packages/google-auth/google/auth/_regional_access_boundary_utils.py Outdated

Comment thread packages/google-auth/google/auth/credentials.py

macastelaz force-pushed the clean-rab-gcloud branch from 0785de5 to 23ad64b Compare April 20, 2026 17:01

macastelaz and others added 5 commits April 23, 2026 19:14

feat(auth): implement blocking lookup flow for regional access boundary

5c3c331

style(auth): address lint and formatting issues in regional access bo…

c6c140f

…undary implementation

fix(auth): restore accidentally removed helper and fix flakiness in s…

b0163b1

…ystem tests

Rename method for internal access boundary seeding

17a1c3d

Renamed 'with_regional_access_boundary' to '_with_regional_access_boundary' to indicate internal use.

Update credentials.py

78bd7e6

Update the comment block of "_with_regional_access_boundary" to inform future maintainers of the necessity to maintain a backwards compatible contract of this method.

macastelaz force-pushed the clean-rab-gcloud branch from 7686ffb to 78bd7e6 Compare April 23, 2026 19:23

macastelaz added 2 commits April 23, 2026 19:25

chore(auth): remove redundant get_bool_from_env helper

9bbba81

chore(auth): revert accidental changes to _helpers.py

5a8ad8b

macastelaz force-pushed the clean-rab-gcloud branch from 8c0bcee to 81a2d2c Compare April 23, 2026 19:34

chore(auth): remove unused __eq__ implementations

87880a6

macastelaz force-pushed the clean-rab-gcloud branch from 03803f7 to 87880a6 Compare April 23, 2026 19:42

macastelaz added 2 commits April 23, 2026 19:48

test(auth): increase coverage for regional access boundary

ac15926

test(auth): add coverage for real credential types and blocking lookup

1872dd1

macastelaz force-pushed the clean-rab-gcloud branch from 4bd1c9c to 1872dd1 Compare April 23, 2026 20:34

style(auth): apply black formatting

28541d4

macastelaz changed the title ~~Blocking Regional Access Boundary Lookup and Seed Support~~ feat(auth): Add blocking Regional Access Boundary Lookup and Seed Support Apr 23, 2026

macastelaz marked this pull request as ready for review April 23, 2026 20:37

macastelaz requested review from a team as code owners April 23, 2026 20:37

macastelaz assigned daniel-sanche and nbayati Apr 23, 2026

fix: fix failing pickling tests by restoring _rab_manager and adding …

d2258f4

…__eq__

nbayati reviewed Apr 24, 2026

View reviewed changes

macastelaz added 3 commits April 24, 2026 15:29

style(auth): fix black formatting and typo

bf41e71

test(auth): fix flaky assertion in test_external_accounts.py

4e2bc63

nbayati reviewed Apr 24, 2026

View reviewed changes

Comment thread packages/google-auth/tests/test__regional_access_boundary_utils.py

nbayati approved these changes Apr 24, 2026

View reviewed changes

test(auth): verify no request made when RAB lookup URL is null

d4ab1eb

macastelaz assigned ohmayr Apr 24, 2026

ohmayr added the do not merge Indicates a pull request not ready for merge, due to either quality or timing. label Apr 27, 2026

parthea self-assigned this Apr 28, 2026

gemini-code-assist Bot reviewed Apr 29, 2026

View reviewed changes

daniel-sanche reviewed Apr 29, 2026

View reviewed changes

refactor: address PR feedback for Regional Access Boundary

2f53d4f

daniel-sanche approved these changes Apr 30, 2026

View reviewed changes

test(auth): rename parameter in unit tests

53bb27e

daniel-sanche removed the do not merge Indicates a pull request not ready for merge, due to either quality or timing. label Apr 30, 2026

daniel-sanche merged commit 134e3af into googleapis:main Apr 30, 2026
31 checks passed

Conversation

macastelaz commented Apr 20, 2026

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

nbayati left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

nbayati left a comment

Choose a reason for hiding this comment

Uh oh!

daniel-sanche commented Apr 29, 2026

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

gemini-code-assist Bot Apr 29, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

daniel-sanche left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

daniel-sanche left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants